////////////////////////////////////////////////////////////////////////////////
// Skrypcik                                                                   //
// Plugin umoliwiajcy manewrowanie wysyanymi i odbieranymi wiadomociami.  //
//                                                                            //
// Autor:   Pawe Konarski                                                    //
// GG:      513761                                                            //
// Tlen.pl: dziobu@tlen.pl                                                    //
// e-mail:  kpawel@kr.onet.pl                                                 //
// www:     narazie.nie.ma                                                    //
////////////////////////////////////////////////////////////////////////////////

Konfiguracja polega na napisaniu skryptu, ktry bdzie si wykonywa przy kadym
wysaniu/odebraniu wiadomoci. Skrypt pisze si w jzyku assemblero-podobnym.

.......................
OGRANICZENIA:
 - kada linia to jeden rozkaz
 - nie ma mozliwoci tworzenia zoe funkcji

.......................
KOMENTARZE to w linii wszystko po znakach '//'. Nie ma komentarzy
wielolinijkowych.

.......................
ETYKIETY to zaznaczone miejsca w programie. Nie wykonuj nic. Informuj tylko
do ktrego miejsca w skrypcie naley skoczy (np polecenie "goto", "call").
Etykieta to cig znakw, poprzedzony dwukropkiem.

Przykad uycia etykiet do utworzenia ptli:

mov $a, 5          // ustawiam warto $a na 5
:petla
//.........
send 1234,'test'   // jakietam rozkazy
//.........

subb $a, 1         // odejmuje 1 od $a
if $a <= 0         // jeli $a jest mniejsze bd rwne 0 to
goto koniec_petli  // wychodz z ptli
goto petla         // a jesli nie - skacze na pocztek ptli
:koniec_petli

Istniej te etykiety o specjalnym przeznaczeniu:
  :_INIT - jeli istnieje to plugin skoczy do niej po zaadowaniu skryptu.
           Jej przeznaczeniem jest inicjacja wartoci zmiennych uywanych
           pniej w programie. Pewne polecenia mog w niej nie dziaa
           (np "send" - poniewa przy adowaniu wtyczki moe jeszcze nie by
           komunikacji z serwerem, itp);
           Wchodzc do niej plugin nie ustawia adnych zmiennych specjalnych.

  :_START - zaznacza miejsce pocztku wykonywania skryptu. W momencie gdy trzeba
           bdzie wykona skrypt plugin skoczy do tej etykiety. Gdy jej nie
           znajdzie - skrypt bdzie wykonywany od pocztku.
           Tutaj plugin ustawia (obsuguje) nastpujce zmienne specjalne:
             $_ID      - ID nadawcy/odbiorcy (zaley czy wiadomo odbierana
                         czy wysyana)
             $_PROTO   - protok ('GG' lub 'TLEN' - patrz: stae)
             $_MESSAGE - tre wiadomoci
             $_IN      - czy wiadomo IN (= #TRUE - wiadomoc przychodzca)
             $_FILTR   - czy wiadomo ma by filtrowana (domylnie: #FALSE)

  :_MENU_SHOW - jeli istnieje, bdzie wykonane gdy elementy menu bd
           pokazywane. W tym miejscu mona zmieni rne parametry elementw
           w menu (np. nazwa czy widoczno)
           Zmienne specjalne:
           $_ID - ID usera na ktrym kliknito myszk

  :_MENU_CLICK - obsuga kliknicia pozycji w menu; Zmienne specjalne:
           $_ID        - ID usera na ktrym kliknito myszk
           $_MENU_ITEM - nazwa menu na ktrym kliknito

.......................
ZMIENNE:
Zmienne mog skada si tylko z liter i cyfr; nazwa musi by poprzedzona
znakiem dolara "$". S 2 typy zmiennych: liczbowe i tekstowe. Konwersja midzy
nimi dziaa automatycznie - w zalenoci gdzie si dalej zmiennej uywa.
Zapis liczbowy to po prostu liczba (1234), tekst natomiast naley ogranicza
znakami cudzysowiu (pojedycze) "'" ('abcd').

Pod ktem operacji bitowych:
Przez "liczb" rozumiemy 32 bitow liczb ze znakiem (Integer w Pascalu,
Int w C).

W tekcie mona wstawi znak koca linii: '\n'. Przykad:
mov $a, 'pierwsza linia\ndruga linia'

Zmienne trac pamitane wartoci dopiero po zamkniciu tlena (bad wyczenia
wtyczki), tak wic za kadym uruchomieniem skryptu zmienne maj wartoci
z poprzedniego uruchomienia skryptu. Wyjtkami s zmienne z ustawionym
znacznikiem SAVE (patrz rozkaz SAVE).

ZMIENNE SPECJALNE:
Zmienne te nie s w jaki sposb traktowane specjalne przez wtyczke. Mozna je
dowolnie modyfikowa. Z tym, e zmiana $_MESSAGE powoduje zmian treci
wiadomoci - ale z nieznanych przyczyn dziaa tylko na wiadomoci odebrane;
a wartoci $_FILTR okrela si czy wiadomo ma dotrze do odbiorcy czy nie.

.......................
Wartoci specjalne:
Do zmiennych liczbowych mona wpisywa rwnie dane w formacie bitowym. Dane
wpisujemy podajc bity (0 i 1) poprzedzone znakiem 'B':

mov $liczba, B00001101   // $liczba = 13

.......................
STAE:
W programie mona uywa predefiniowanych wartoci; s to stae (ich nazwa
zaczyna si znakiem '#').

Lista staych i przypisanych im wartoci:

  Wartoci logiczne:
    #TRUE  = 1
    #FALSE = 0

  Protokoy:
    #PROTO_TLEN = TLEN
    #PROTO_GG   = GG

  Statusy:
    #STS_OFFLINE   = 1   - Tlen/GG(nie dostpny)
    #STS_ONLINE    = 2   - Tlen/GG(dostpny)
    #STS_CHAT      = 3   - Tlen
    #STS_DND       = 4   - Tlen
    #STS_AWAY      = 5   - Tlen/GG(zaraz wracam)
    #STS_XA        = 6   - Tlen
    #STS_INVISIBLE = 7   - Tlen/GG(niewidoczny)

  Info kontaktu - flagi:
    #CINFO_ONLINE    = 1       - dostpny
    #CINFO_OFFLINE   = 2       - niedostpny
    #CINFO_WAITAUTH  = 4       - oczekiwanie na autoryzacj
    #CINFO_NOTAUTH   = 8       - brak autoryzacji
    #CINFO_PHONE     = 16      - numer telefonu
    #CINFO_NOTINLIST = 32      - spoza listy kontaktw
    #CINFO_BLOCKED   = 65536   - zablokowany

.......................

I to chyba tyle...
////////////////////////////////////////////////////////////////////////////////
Opis sterowania pluginem z poziomu Ducha. (wymaga wczonego pluginu Duch_Tlen)
Zapis w Duchu:
<tlen.plug Skrypcik Funkcja Parametry>
 -> Funkcja - nazwa funkcji do wywoania
 -> Parametry - dane do tej funkcji

Obsugiwane funkcje:
 -> MOV - funkcja ustawia warto zmiennej
  - Parametry - zgodnie z parametrami polecenia "mov"
  Przykad:
  <tlen.plug Skrypcik MOV $a, 'tekst'>
////////////////////////////////////////////////////////////////////////////////
                                OPIS ROZKAZW

--------------------------------------------------------------------------------
Opis skrtw:
  $zm   - zmienna (warto pobrana ze zmiennej)

  $res  - zmienna w ktrej zostanie zapisany wynik
          czasem te z niej brana jest warto do funkcji (patrz np. ADD)
          W przypadku gdy funkcja zwraca kilka wartoci z ktrych nie interesuj
          nas wszystkie, mona nie podawa nic w miejscu na "$res".

  const - jaka staa (liczba, tekst); np:
          1234     - to jest liczba 1234
          '1234'   - to jest tekst 1234

  oper  - operator logiczny:
          =       - rwne
          <>, !=  - rne
          >       - wieksze
          <       - mniejsze
          >=      - wiksze bd rwne
          <=      - mniejsze bd rwne

  bool  - warto logiczna (prawda, fasz). S 2 sposoby okrelania tej wartoci:
          1. przez stae:
             #TRUE  - prawda
             #FALSE - fasz
          2. przez wartoci zmiennych liczbowych:
             0    - fasz
             <> 0 - prawda (warto liczbowa rna ni 0)

--------------------------------------------------------------------------------
GOTO nazwa_etykiety
  Skacze do etykiety.

  Przykad 1:

  goto etykieta   // skok do etykiety
  mov $a, 0       // ten kod nigdy si nie wykona
  :etykieta       // deklaracja etykiety

  Przykad 2:

  mov $a, 10      // wpisanie 10 do $a
  :petla          // deklaracja etykiety

  if $a <= 0      // jeli $a <= 0 to
  goto koniec     // skocz do etykiety "koniec"
                  // a jesli nie
  subb $a, 1      // zmniejsz $a o 1

  goto petla      // skok do etykiety
  :koniec
--------------------------------------------------------------------------------
IF $zm/const <oper> $zm/const
  Jeli warunek jest prawdziwy to wykonuje nastpn operacj.
  Jeli nie, skacze dwie operacje dalej.
  UWAGA !!!
  Nie istnieje /jeszcze/ nic takiego jak else !!!

  Przykad:

  mov $a, 1                    // $a := 1
  mov $b, 'a jest rne od 1'  // wpisanie tekstu do $b
  if $a = 1                    // jesli $a = 1
  mov $b, 'a jest rwne 1'     // wpisanie tekstu do $b
  send 1234, $b                // ta instrukcja si wykona niezalenie od if

--------------------------------------------------------------------------------
MOV $res, $zm/const
  Kopiuje do $res warto z $zm/const.

  Przykad:

  mov $a, 1       // wpisz 1 do $a
  mov $b, 'abcd'  // wpisz 'abcd' do $b
  mov $a, $b      // wpisz do $a warto z $b

--------------------------------------------------------------------------------
EXIT
  Powoduje wyjcie ze skryptu.

  Przykad:

  if $_ID = 1234 // jeli ID nadawcy = 1234
  exit           // zakocz przetwarzanie skryptu

--------------------------------------------------------------------------------
SEND $zm/const(id), $zm/const(wiadomo)
  Wysya wiadomo do osoby (id).

  Przykad:

  send 1234, 'Czesc'         // wyslij "Czesc" do 1234
  send test@tlen.pl, 'Czesc' // wyslij "Czesc" do test@tlen.pl

  mov $a, 'Czesc'            //
  send 1234, $a              // wyslij "Czesc" do 1234
  
--------------------------------------------------------------------------------
SAVE zm, bool
  Ustawia znacznik, czy warto zmiennej ma by zapamitywania przy zamykaniu
  komunikatora (i odtwarzana przy starcie).

  Przykad:

  save $a, #TRUE

--------------------------------------------------------------------------------
ADD $res, $zm/const
  Dodaje do $res warto z $zm/const i wynik wpisuje do $res.

  Przykad:

  mov $a, 1
  mov $b, 2
  add $a, $b
  // teraz $a ma warto 3

--------------------------------------------------------------------------------
SUBB $res, $zm/const
  Odejmuje od $res warto z $zm/const i wynik wpisuje do $res.

  Przykad:

  mov $a, 10
  mov $b, 4
  subb $a, $b
  // teraz $a ma warto 6

--------------------------------------------------------------------------------
MUL $res, $zm/const
  Mnoy warto z $res z $zm/const i wynik wpisuje do $res.

  Przykad:

  mov $a, 10
  mov $b, 4
  mul $a, $b
  // teraz $a ma warto 40

--------------------------------------------------------------------------------
DIV $res, $zm/const
  Dzieli (cakowicie) warto z $res przez $zm/const i wynik wpisuje do $res.

  Przykad 1:

  mov $a, 10
  mov $b, 4
  div $a, $b
  // teraz $a ma warto 2

  Przykad 2:

  mov $a, 100
  mov $b, 25
  div $a, $b
  // teraz $a ma warto 4

--------------------------------------------------------------------------------
STRCON $res, $zm/const, $zm/const,...
  czy stringi (cigi tekstowe) i wynik wpisuje do $res. Ilo stringw nie
  jest ograniczona.

  Przykad:

  mov $a, 'ala ma'     // $a := 'ala ma'
  mov $b, 'kota'       // $b := 'kota'
  strcon $a, ' ', $b   // $a = 'ala ma kota'

--------------------------------------------------------------------------------
STRLEN $res, $zm/const
  Do $res wpisuje dugo tekstu w $zm/const.

  Przykad:

  strlen $a, 'abcd'   // $a = 4
  strlen $b, $a       // $b = 1  (bo dugo '4' = 1)

--------------------------------------------------------------------------------
STRCOPY $res, $zm/const(tekst), $zm/const(index), $zm/const(count)
  Do $res jest kopiowane "count" znakw z "tekst", od znaku numer "index"
  (wcznie).

  Przykad:

  strcopy $a, 'ala ma kota', 5, 2  // kopiowanie 2 znakw, od znaku 5
    // teraz $a ma warto "ma"

--------------------------------------------------------------------------------
STRDEL $res, $zm/const(index), $zm/const(count)
  Z tekstu $res jest usuwanych "count" znakw, od znaku numer "index" (wcznie).

  Przykad:

  mov $a, 'ala ma kota'
  strdel $a, 1, 3        // usuwanie trzech pierwszych znakw
                         // teraz $a ma warto ' ma kota'

--------------------------------------------------------------------------------
STRPOS $res, $zm/const(substr), $zm/const(str)
  Do $res wpisuje index wystpienia cigu "substr" w "str". W przypadku gdy
  dany tekst nie zosta znaleziony, zwracana wartoc to 0.

  Przykad:

  mov $a, 'spam'
  mov $b, 'To nie jest spam'
  strpos $poz, $a, $b
    // w $poz jest liczba 13

--------------------------------------------------------------------------------
STREXT $zm/const(tekst), $zm/const(znak rodz.), $zm/const(index), $res
  Rozdziela "tekst" na tablic wg "znakw rodzielajcych" i do $res wpisuje
  element o indeksie "index".
  Uwaga 1."znak rozdzielajcy" to jeden znak. W przypadku podania wikszej
    iloci znakw, pod uwag zostanie wsity tylko pierwszy znak.
  Uwaga 2. Index jest liczony od zera !!!
  Uwaga 3. W przypadku gdy index ley poza zakresem tablicy, zwracany jest
    pusty tekst.

  Przykad:

  mov $a, 'jaki tekst;tekst drugi;tekst trzeci'
  mov $a, ';', 2, $wyn
  // tutaj $wyn wynosi "tekst trzeci"

--------------------------------------------------------------------------------
STRTRIM $res
  Usuwa spacje na pocztku i na kocu tekstu.

  Przykad:

  mov     $a, '  abcdef   '
  strtrim $a
  // teraz $a = 'abcdef'

--------------------------------------------------------------------------------
STRUP $res(tekst)
  Zmienia wszystkie litery na due.

  Przykad:
  mov   $a, 'Test'
  strup $a
  // $a = 'TEST'

--------------------------------------------------------------------------------
STRLOW $res(tekst)
  Zmienia wszystkie litery na mae.

  Przykad:
  mov   $a, 'Test'
  strup $a
  // $a = 'test'

--------------------------------------------------------------------------------

CHKSPAM $res, $zm/const
  Sprawdza czy podany tekst ($zm/const) to spam. Jeli tak, do $res wpisuje
  #TRUE, jeli nie - #FALSE

  Przykad:

  chkspam $a, $_MESSAGE             // do $a znacznik czy to spam
  if $a = #TRUE                     // jeli to jest spam
  send $_ID, 'Nie chce spamu !!!'   // to wyslij odpowied

--------------------------------------------------------------------------------
SETSTS $zm/const(proto), $zm/const(status), $zm/const(opis)
  Ustawia status dla protokou "proto". Wartoci przyjmowane przez "proto" oraz
  przez "status" znajduj si na licie staych programu.

  Przykad:

  setsts #PROTO_GG, #STS_ON, 'Opis...'

--------------------------------------------------------------------------------
READSTS $zm/const(proto), $res(status), $res(opis)
  Pobiera status dla protokou "proto". Wartoci przyjmowane przez "proto" oraz
  przez "status" znajduj si na licie staych programu.

  Przykad:

  readsts #PROTO_TLEN, $status, $opis

--------------------------------------------------------------------------------
GETDATE $res(rok), $res(miesic), $res(dzie)
  Zwraca w 3 zmiennych bieacy rok, miesic i dzie.

  Przykad:

  getdate $rok, $miesiac, $dzien

--------------------------------------------------------------------------------
GETTIME $res(godzina), $res(minuta), $res(sekunda)
  Zwraca w 3 zmiennych biec godzin, minut i sekund.

  Przykad:

  gettime $godzina, $minuta, $sekunda

--------------------------------------------------------------------------------
CHKINT $res(bool), $zm/const(tekst)
  Sprawdza czy "tekst" jest poprawn liczb. Wynik (#TRUE, #FALSE) zwraca
  w $res.

  Przykad:

  mov $a, '1234'
  chkint $czyL, $a
  // $czyL = #TRUE

--------------------------------------------------------------------------------
BITAND $res(liczba), $zm/const(liczba)
  Bitowe "AND". Podane wartoci musz by liczbowe.

  Przykad:

  mov $a, 1
  mov $b, 2
  bitand $a, $b
  // $a = 0

--------------------------------------------------------------------------------
BITOR $res(liczba), $zm/const(liczba)
  Bitowe "OR". Podane wartoci musz by liczbowe.

  Przykad:

  mov $a, 1
  mov $b, 2
  bitor $a, $b
  // $a = 3

--------------------------------------------------------------------------------
BITXOR $res(liczba), $zm/const(liczba)
  Bitowe "XOR". Podane wartoci musz by liczbowe.

  Przykad:

  mov $a, 1
  mov $b, 2
  bitxor $a, $b
  // $a = 3

--------------------------------------------------------------------------------
BITNOT $res(liczba)
  Bitowe "NOT". Podana warto musi by liczbowa.

  Przykad:

  mov $a, 1
  bitnot $a
  // $a = -2

--------------------------------------------------------------------------------
BITSHR $res(liczba), $zm/const(ile przes)
  Przesunicie bitw o "ile przes" miejsc w prawo. Podane wartoci musz by
  liczbowe.

  Przykad:

  mov $a, 2
  bitshr $a, 1
  // $a = 1

--------------------------------------------------------------------------------
BITSHL $res(liczba), $zm/const(ile przes)
  Przesunicie bitw o "ile przes" miejsc w lewo. Podane wartoci musz by
  liczbowe.

  Przykad:

  mov $a, 2
  bitshl $a, 1
  // $a = 4

--------------------------------------------------------------------------------
CONINFO $zm/const(id), $res(nazwa), $res(grupa), $res(opis), $res(flagi)
  Zwraca informacje o kontakcie. Dane wejciowe: "id". Rozkaz zwraca:
  - nazw kontaktu - "nazwa"
  - nazw grupy w ktrym jest kontakt - "grupa"
  - opis kontaktu - "opis"
  - flagi (dodatkowe informacje o kontakcie - patrz na licie staych "Info
    kontaktu - flagi")

  Przykad:

  coninfo '1234', $nazwa, $grupa, $opis, $flagi  

--------------------------------------------------------------------------------
CALL nazwa_etykiety
  Skacze do etykiety i zapamituje bieac pozycj.

  Przykad:

  mov   $a, 10          // $a = 10
  mov   $b, 5           // $b = 5
  call  dodaj           // wywoanie procedury
  send  1234, $a        // wysanie wyniku (teraz $a bdzie rwne 15)


  :dodaj
  add   $a, $b          // dodanie $a + $b
  ret                   // powrt do miejsca z ktrego zostalo wywoane call

--------------------------------------------------------------------------------
RET (brak parametrw)
  Powraca do miejsca z ktrego zostalo wywoane CALL (patrz przykad CALL).

--------------------------------------------------------------------------------
MENUADD $zm/const(id menu), $zm/const(tekst)
  Dodaje now pozycje w menu wtyczki (lub zmienia nazw ju istniejacej).

  Przykad:

  MenuAdd 'ITEM 1', 'Kliknij tu'

--------------------------------------------------------------------------------
MENUDEL $zm/const(id menu)
  Usuwa pozycje z menu wtyczki.

  Przykad:

  MenuDel 'ITEM 1'

--------------------------------------------------------------------------------
MENUSHOW $zm/const(id menu), $zm/const(bool)
  Ustawia status ukryty/widoczny pozycji z menu.

  Przykad:

  MenuShow 'ITEM 1', #TRUE

--------------------------------------------------------------------------------
SAVECONFIG (brak parametrw)
  Zapisuje ustawienia i wartoci pamitanych zmiennych)
  
--------------------------------------------------------------------------------

